Skip to content

Rewrite FAQ paradigm answer and improve clarity - #21

Merged
koriym merged 2 commits into
masterfrom
faq-paradigm-rewrite
Mar 24, 2026
Merged

koriym merged 2 commits into
masterfrom
faq-paradigm-rewrite

Conversation

@koriym

@koriym koriym commented Mar 24, 2026 •

Copy link
Copy Markdown
Contributor

Summary

  • Q0: 「パラダイムか?」の回答をHOW/WHAT/WHETHER の問いの転換として再構成
  • Q1: 「興味深いことに…」の主観的段落を削除
  • Q1-a: CQRS未知の読者向けに定義を追加
  • Q2: OOP/FP回答を簡潔に
  • Q11: Q2への内部参照を削除、自立した回答に
  • Q15, Q16: 冗長な表現をカット
  • Q23: プロパティ宣言をコンストラクタの前に移動

Test plan

  • Jekyll buildが通ること
  • 日英FAQページの表示確認

Summary by CodeRabbit

  • Documentation

    • Reworded FAQ answers for clearer framing of the paradigm, patterns vs paradigms, OOP/FP integration, CQRS and DB/API separation; emphasized stepwise migration and refined concept descriptions in both English and Japanese.
  • Code Examples

    • Adjusted sample snippets in the FAQ for improved clarity and readability.

- Q0: Replace assertion with HOW/WHAT/WHETHER progression
- Q1: Remove "interestingly" editorial paragraph
- Q1-a: Add CQRS definition for readers without prior knowledge
- Q2: Simplify OOP/FP answer
- Q11: Remove internal Q2 reference, make self-contained
- Q15, Q16: Trim redundant phrasing
- Q23: Move property declarations before constructor
@coderabbitai

coderabbitai Bot commented Mar 24, 2026 •

Copy link
Copy Markdown
Contributor

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 85f89d71-f711-49e1-bb9b-76c1b626ee58

📥 Commits

Reviewing files that changed from the base of the PR and between 39f2e45 and f0b9006.

📒 Files selected for processing (1)
  • manuals/1.0/ja/14-faq.md

📝 Walkthrough

Walkthrough

Rewrites in English and Japanese FAQ files that reframe the core positioning (patterns vs paradigms), tighten answers on MVC/DDD, CQRS, OOP/FP, side-effect orchestration, integration/migration, and DB/API separation, plus a PHP ValidatedUser snippet where public properties are moved to the class body before the constructor.

Changes

Cohort / File(s) Summary
FAQ Documentation
manuals/1.0/en/14-faq.md, manuals/1.0/ja/14-faq.md
Reworded TL;DR and multiple Q&A entries to shift framing from "new programming paradigm" to pattern/paradigm distinctions; simplified CQRS, OOP/FP, side-effect, integration/migration, and DB/API descriptions. Moved public string $display; and public bool $isValid; declarations into the ValidatedUser PHP class body before the constructor and removed duplicate post-constructor declarations. Added blank lines before several Japanese subsection headings (formatting only).

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

Poem

🐇 I hopped through FAQs with a nibble and cheer,
Moved properties forward so code’s bright and clear.
Patterns hum softly, paradigms sigh,
A rabbit’s small tweak helps the docs reach the sky. ✨

🚥 Pre-merge checks | ✅ 3
✅ Passed checks (3 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title 'Rewrite FAQ paradigm answer and improve clarity' directly aligns with the primary changes—rewriting the paradigm answer (Q0) and improving FAQ clarity through simplified phrasing, removed redundancies, and better definitions across multiple questions.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch faq-paradigm-rewrite

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

@claude

claude Bot commented Mar 24, 2026

Copy link
Copy Markdown

PR Review: FAQ Paradigm Rewrite

Overall this is a focused, well-scoped documentation PR. The changes improve clarity and conciseness throughout.

Positives

  • Q0 HOW/WHAT/WHETHER framing is memorable and genuinely clarifies the paradigm concept
  • Q1-a: adding a CQRS definition before the Be-specific commentary helps readers unfamiliar with the pattern
  • Q23 property ordering: moving properties before the constructor is idiomatic PHP 8.x for readonly classes. Correct fix.
  • Removing the subjective "Interestingly..." paragraph (Q1) and the Q2 cross-reference in Q11 are clean cuts.

Issue: Q0 — Implicit answer to an explicit question

The question is "Is this a new programming paradigm?" The original answered "Yes." explicitly. The rewritten answer defines what a paradigm is and demonstrates that Be qualifies, but never states the affirmative. A reader could finish without a clear conclusion. Consider leading with it: "A. Yes — and in a specific sense. A pattern is a better answer to an existing question. A paradigm changes the question itself."

Issue: Q2 — Lost motivating contrast

The removed paragraph explained why Be differs from OOP by contrasting original intent vs. common practice ("objects become obedient data containers"). The one-sentence replacement states what Be does but loses the contrast that makes it meaningful. This content was load-bearing for readers asking "OOP already claims autonomy — why is Be different?"

Issue: Q16 — "Why" removed

The deleted sentence — "Persistence and external communication are implementation details, not user concerns" — gave the design rationale for confining DB/API work to Reason. The current version communicates the benefit (freed from schemas) but omits the principle. For a philosophy-forward framework, the principle is often what readers need to internalize.

Minor

Blank line before --- in Japanese frontmatter: a blank line was added between permalink: and --- in ja/14-faq.md. Jekyll tolerates this, but it is inconsistent with the English file and every other page in the repo.

No concerns on security, performance, test coverage (documentation-only changes), or Jekyll build compatibility.

@koriym
koriym merged commit 694fb1c into master Mar 24, 2026
1 check was pending
@koriym
koriym deleted the faq-paradigm-rewrite branch March 24, 2026 15:52
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant